Skip to main content
Version: 1.0.0

createProductDocument

Function Names: createOrUpdateProductDocument / createOrUpdateProductDocumentWithCatalogRef

Author: Domenico Cerone Creation Date: 25/09/2025
Last Reviewer: Domenico Cerone

Trigger: Called by populateVariantFromSku and populateVariantFromExcel

Purpose: Manages creation and updating of documents in the 'Products' Firestore collection from mapped JSON data and variant information. Handles the complete product lifecycle with automatic tag aggregation, brand management, and multi-language support.

Detailed Functionality​

This component function handles the complete Products collection management with a sophisticated 3-step workflow for both new products and existing product updates. Includes thread-safe tag creation system with mutex synchronization to prevent duplicates in high-concurrency scenarios.

1. PRODUCT EXISTENCE CHECK​

  • Searches in 'Products' collection for document with modelName equal to glassesName
  • If EXISTS → updates fields and adds/updates variant in variants_map (STEP 3)
  • If NOT EXISTS → creates new complete product document (STEP 2)

2. NEW PRODUCT CREATION​

  • Creates document with complete base structure
  • Populates fields from mapped JSON
  • Creates variants_map with current variant
  • Sets availableVariants = 0 (managed externally)
  • Uses Firestore auto-generated ID

3. EXISTING PRODUCT UPDATE​

  • Updates product fields from mapped JSON
  • Verifies if variant already exists in variants_map
  • If variant doesn't exist → adds new entry
  • If variant exists → updates existing entry
  • Updates availableVariants with real count
  • Updates list_frame_color_tags, list_size_tags, etc.

Fields Populated from Mapped JSON​

Base Product Fields​

  • modelName ← glassesName (main identifier)
  • age ← catAgeForGender
  • manufacturedProductStatus ← manufacturedProductStatus
  • rxAble ← rxAble (converted from "YES"/"NO" to boolean true/false)
  • mainBrandRef ← Brand ID (find/create in MainBrands collection)

Image Fields (from current variant)​

  • imgUrl ← poster
  • thumbnail ← poster
  • urlImage ← poster

Timestamp Fields​

  • lastUpdate ← current timestamp (always updated, Date object)
  • productReleaseDate ← productReleaseDate (if present in mapped JSON, Date object)
  • productEndDate ← productEndDate (if present in mapped JSON, Date object)

Multi-language Descriptions​

  • descriptionEn ← description_en
  • descriptionIt ← description_it
  • descriptionEs ← description_es
  • descriptionFr ← description_fr
  • descriptionDe ← description_de

Tag Arrays (aggregated from all variants)​

  • list_frame_color_tags ← [frameColor tag IDs from all product variants]
  • list_size_tags ← [size tag IDs from all product variants]
  • list_line_tags ← [line tag IDs]
  • list_tags ← [catType, catAgeForGender, catGender, catForma, catMaterialOne, polarised, catLensesTreat, hingeType as tag IDs]

Variant Management​

  • variants_map ← array with entry for each product variant:
    • eanCode, id, publishedInARSLibrary (""), skuCode, upcCode, variantName (glassesName)
  • list_variants ← [IDs of all product variants]
  • availableVariants ← always 0 (logic managed externally)

Tag Aggregation Logic​

Tags are intelligently aggregated from all existing variants belonging to the same product:

Frame Color Tags​

  • For each frameColor creates/finds document in Tags collection
  • Documents have: group="Frame Color", name="COLOR", type="frameColor"
  • IDs aggregated for all product variants

Size Tags​

  • For each size creates/finds document in Tags collection
  • Documents have: group="Size", name="SIZE", type="size"
  • IDs aggregated for all product variants

Line Tags​

  • For each line name creates/finds document in Tags collection
  • Documents have: catalogRef="BRAND_ID", group="Line", name="LINE", type="line"
  • ID used (unique per product since line name doesn't change between variants)

Category Tags (list_tags)​

Advanced tag system with automatic translations:

  • catType → Tag ID with: group="Tipologia", name=catType value, type="tag"
  • catAgeForGender → Tag ID with: group="Age For Gender", name=catAgeForGender value, type="categoria"
  • catGender → Tag ID with: group="Gender", name=translated catGender, type="categoria"
    • "WOMAN" → translated to "Donna"
    • "MAN" → translated to "Uomo"
    • Other values remain unchanged
  • catForma → Tag ID with: group="Forma", name=catForma value, type="tag"
  • catMaterialOne → Tag ID with: group="Materiale", name=catMaterialOne value, type="tag"
  • polarised → Tag ID based on value:
    • "YES" → group="Polarised", name="POLARIZED", type="tag"
    • "NO" → group="Polarised", name="NO POLARIZED", type="tag"
  • catLensesTreat → Tag ID with: group="Treatement", name=catLensesTreat value, type="tag"
  • hingeType → Tag ID with: group="Hinge Type", name=hingeType value, type="tag"

Brand Normalization​

The mainBrandRef field is automatically normalized according to business rules:

  • Hugo brands: "HUGO" → "HUGO EYEWEAR"
  • Boss brands: "HUGO BOSS", "BOSS ORANGE" → "BOSS EYEWEAR"
  • Carrera brands: "CARRERA BY JIMMYCHOO", "CARRERA BIKE", "CARRERA SNOW", "CARRERA DUCATI" → "CARRERA"
  • Polaroid brands: "POLAROID ANCILLARIES", "POLAROID KIDS", "POLAROID STAYSAFE" → "POLAROID"
  • Smith brands: "SMITH FASHION & ACC.", "SMITH BIKE HELMETS", "SMITH SNOW", "SMITH BIKE GOGGLES", "PRIVATE LABEL SMITH", "SUNCLOUD" → "SMITH OPTICS"
  • Other brands remain unchanged

Variants Map Structure​

Each entry in variants_map contains:

  • eanCode ← variant's eanCode (stored at variant level only)
  • id ← variant document ID
  • publishedInARSLibrary ← empty timestamp (future management)
  • skuCode ← variant's skuModel
  • upcCode ← variant's upcCode (stored at variant level only)
  • variantName ← glassesName

Function Parameters​

createOrUpdateProductDocument​

/**
 * @param {Object} mappedJsonData - Mapped JSON data from populateVariantFromSku
 * @param {string} variantDocumentId - ID of created/updated Variants document
 * @param {string} requestId - Request ID for logging
 * @returns {Promise<Object>} Operation result with details
 */

createOrUpdateProductDocumentWithCatalogRef​

/**
 * @param {Object} mappedJsonData - Mapped JSON data from populateVariantFromSku
 * @param {string} variantDocumentId - ID of created/updated Variants document
 * @param {string} requestId - Request ID for logging
 * @param {string} catalogOrderId - CatalogOrder ID (optional)
 * @returns {Promise<Object>} Operation result with details
 */

Response Structure​

Success Response​

{
  "operation": "create",
  "documentId": "auto_generated_product_id",
  "modelName": "TOMMY HILFIGER TH 1950/G",
  "variantsCount": 0,
  "success": true,
  "message": "New Products document created for model TOMMY HILFIGER TH 1950/G"
}

Error Response​

{
  "operation": "error",
  "documentId": null,
  "modelName": "TOMMY HILFIGER TH 1950/G",
  "variantsCount": 0,
  "success": false,
  "message": "Error in Products document management: Missing glassesName",
  "error": "Missing glassesName in mapped data - required for modelName"
}

Default Field Values​

All other fields maintain default values:

  • glassesCode: ""
  • glassesInclinationCoeff: ""
  • glassesInclinationCoeffIos: ""
  • glassesYCoeff: ""
  • glassesYCoeffAndroid: ""
  • glassesZCoeff: ""
  • glassesZCoeffAndroid: ""
  • logLoadingModel: ""
  • multiple3dViewerLink: ""
  • notesNumber: 0
  • priority: 0
  • status: "Incompleto"
  • urlProduct: ""
  • urlShadow: ""

Thread-Safe Tag Management System​

The function implements a sophisticated thread-safe tag creation system to prevent duplicate tags when processing multiple products simultaneously.

Tag Creation Functions​

Brand Management:

  • findOrCreateMainBrand() - Thread-safe brand creation with normalization
  • Automatically normalizes brand names according to business rules
  • Prevents duplicate MainBrands documents in high-concurrency scenarios

Tag Creation (Thread-Safe):

  • findOrCreateFrameColorTag() - Frame color tags with group="Frame Color", type="frameColor" → Calls findOrCreateTagThreadSafe() from tagUtils
  • findOrCreateSizeTag() - Size tags with group="Size", type="size" → Calls findOrCreateTagThreadSafe() from tagUtils
  • findOrCreateLineTag() - Line tags with group="Line", type="line", catalogRef=brandId → Calls findOrCreateTagThreadSafe() from tagUtils
  • findOrCreateCatTypeTag() - Category tags with group="Tipologia", type="tag" → Calls findOrCreateTagThreadSafe() from tagUtils
  • findOrCreateCatGenderTag() - Gender tags with group="Gender", type="categoria" (with translation: WOMAN→Donna, MAN→Uomo) → Calls findOrCreateTagThreadSafe() from tagUtils
  • findOrCreateCatFormaTag() - Shape tags with group="Forma", type="tag" → Calls findOrCreateTagThreadSafe() from tagUtils
  • findOrCreateCatMaterialOneTag() - Material tags with group="Materiale", type="tag" → Calls findOrCreateTagThreadSafe() from tagUtils
  • findOrCreatePolarisedTag() - Polarization tags with group="Polarised", type="tag" (YES→POLARIZED, NO→NO POLARIZED) → Calls findOrCreateTagThreadSafe() from tagUtils
  • findOrCreateCatLensesTreatTag() - Lens treatment tags with group="Treatement", type="tag" → Calls findOrCreateTagThreadSafe() from tagUtils
  • findOrCreateHingeTypeTag() - Hinge type tags with group="Hinge Type", type="tag" → Calls findOrCreateTagThreadSafe() from tagUtils
  • findOrCreateCatAgeForGenderTag() - Age for gender tags with group="Age For Gender", type="categoria" → Calls findOrCreateTagThreadSafe() from tagUtils

Mutex Synchronization System​

Problem Solved: When multiple products with the same tag values are processed in parallel, they could attempt to create the same Tags document simultaneously, leading to duplicates.

Solution: Thread-safe tag creation using findOrCreateTagThreadSafe():

  • Lock Acquisition: Before creating a tag, acquires exclusive lock using tag name + group + type as key
  • Lock Key Format: TAG_CREATE_{group}_{type}_{name}
  • Polling Mechanism: If lock is held, waits with exponential backoff (50ms → 1000ms max)
  • Automatic Cleanup: Expired locks (older than 10 minutes) are automatically cleaned up
  • Granular Locking: Each unique tag combination has its own lock
  • Error Safety: Locks are released in finally blocks to ensure cleanup

Benefits:

  • Prevents duplicate Tags documents
  • Maintains tag consistency across collections
  • Optimizes performance in batch processing scenarios
  • Provides automatic recovery from stuck locks